home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / grafik / bildanzeiger / superview-lib_dev / docs / svdriver_ref_eng.doc < prev    next >
Text File  |  1995-03-09  |  11KB  |  455 lines
  1.  
  2.    $VER: SVDriver_Ref_ENG.doc V1.4 (30.10.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.           Andreas R. Kleinert,
  9.           Grube Hohe Grethe 23,
  10.           D-57074 Siegen,
  11.           Germany.
  12.  
  13.     Phone:  +49-271-331859 (weekdays after 18.00h)
  14.             +49-271-332147 (weekdays after 18.00h)
  15.     EMail:  Fido             Andreas Kleinert 2:2457/345.10
  16.             Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  17.  
  18.       If nothing else works, try one of these Fido-InterNet gateways:
  19.  
  20.             Andreas_Kleinert@p10.f345.n2457.z2.fido.sub.org (Germany)
  21.             Andreas_Kleinert@p10.f345.n2457.z2.fidonet.org  (US)
  22.  
  23.  
  24.    * DO _NEVER_ ACCESS ANY SVDRIVERS DIRECTLY.
  25.    * DO NEVER BYPASS superview.library !
  26.  
  27.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVDRIVERS :
  28.  
  29.    Here is a listing of the function set, which any of the version 1
  30.    SVDrivers does contain, in an Autodoc-like style of description :
  31.  
  32.         SVD_AllocHandle            ; since Version 1
  33.         SVD_FreeHandle
  34.         SVD_CloseDisplay
  35.         SVD_FreeResources
  36.         SVD_SetGfxBuffer
  37.         SVD_DisplayGfxBuffer
  38.         SVL_SetScreenType
  39.         SVD_SetWindowFlags
  40.         SVD_SetWindowIDCMP
  41.         SVD_GetScreenAddress
  42.         SVD_GetWindowAddress
  43.  
  44.  (you will never find any notes belonging to "BUGS", because any SVDriver
  45.   may have its own ...)
  46.  
  47. -----------------------------------------------------------------------------
  48.    Functions available since Version 1 :
  49. -----------------------------------------------------------------------------
  50.  
  51.    NAME
  52.         SVD_AllocHandle
  53.  
  54.    SYNOPSIS
  55.  
  56.         APTR SVD_AllocHandle(APTR future)
  57.         D0   -$1e            A1
  58.  
  59.    FUNCTION
  60.  
  61.         Allocates a handle for displaying a GfxBuffer via this SVDriver.
  62.  
  63.    INPUT(S)
  64.  
  65.         future - always NULL yet
  66.  
  67.    RESULT
  68.  
  69.         A pointer to a new allocated Handle or NULL, if allocation failed.
  70.  
  71.    WARNING
  72.  
  73.         Test, if the result was NULL, or not !
  74.  
  75.    SINCE
  76.  
  77.         ... Version 1 SVDrivers.
  78.  
  79.    SEE ALSO
  80.  
  81.         SVD_FreeResources, SVD_FreeHandle
  82.  
  83. -----------------------------------------------------------------------------
  84.  
  85.    NAME
  86.         SVD_FreeHandle
  87.  
  88.    SYNOPSIS
  89.  
  90.         VOID SVD_FreeHandle(APTR handle)
  91.         D0   -$24           A1
  92.  
  93.    FUNCTION
  94.  
  95.        Aborts showing, frees all Resources and delocates a Handle, which has
  96.        been allocated with SVD_AllocHandle before.
  97.  
  98.  
  99.        For programmers of SVDrivers :
  100.  
  101.        Note, that this function should call
  102.  
  103.           SVD_CloseDisplay(SVHandle);
  104.           SVD_FreeResources(SVHandle);
  105.  
  106.        internally always. Otherwise memory might be lost, because
  107.        superview.library might only make a call to SVO_FreeHandle(),
  108.        without closing the display/freeing the resources before.
  109.  
  110.    INPUT(S)
  111.  
  112.         handle - a valid handle
  113.  
  114.    RESULT
  115.  
  116.         -
  117.  
  118.    SINCE
  119.  
  120.         ... Version 1 SVDrivers.
  121.  
  122.    SEE ALSO
  123.  
  124.         SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeResources
  125.  
  126. -----------------------------------------------------------------------------
  127.  
  128.    NAME
  129.         SVD_CloseDisplay
  130.  
  131.    SYNOPSIS
  132.  
  133.         VOID SVD_CloseDisplay(APTR handle)
  134.         D0   -$2a             A1
  135.  
  136.    FUNCTION
  137.  
  138.         Aborts showing the Graphic, indentified by the handle.
  139.         The Display-Screen is closed, but no other resources are given free.
  140.  
  141.    INPUT(S)
  142.  
  143.         handle - a valid handle
  144.  
  145.    RESULT
  146.  
  147.         -
  148.  
  149.    SINCE
  150.  
  151.         ... Version 1 SVDrivers.
  152.  
  153.    SEE ALSO
  154.  
  155.         SVD_FreeResources, SVD_FreeHandle
  156.  
  157. -----------------------------------------------------------------------------
  158.  
  159.    NAME
  160.         SVD_FreeResources
  161.  
  162.    SYNOPSIS
  163.  
  164.         VOID SVD_FreeResources(APTR handle)
  165.         D0   -$30              A1
  166.  
  167.    FUNCTION
  168.  
  169.         Frees all resources belonging to the specific Graphic,
  170.         indentified by the handle, which are not needed to just show it.
  171.         The Display will not be closed.
  172.  
  173.    INPUT(S)
  174.  
  175.         handle - a valid handle
  176.  
  177.    RESULT
  178.  
  179.         -
  180.  
  181.    SINCE
  182.  
  183.         ... Version 1 SVDrivers.
  184.  
  185.    SEE ALSO
  186.  
  187.         SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeHandle
  188.  
  189. -----------------------------------------------------------------------------
  190.  
  191.    NAME
  192.         SVD_SetGfxBuffer
  193.  
  194.    SYNOPSIS
  195.  
  196.         ULONG SVD_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  197.         D0    -$36             A1           A2
  198.  
  199.                                ULONG future)
  200.                                A3
  201.  
  202.    FUNCTION
  203.  
  204.         Initializes the given handle with a pointer to a SV_GfxBuffer, which
  205.         should be used with the next call of SVD_DisplayGfxBuffer (see there).
  206.  
  207.         This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated
  208.         (see documentation of SVObjects and superviewsupport.library)
  209.         and may still be displayed via SVD_DisplayGfxBuffer or saved
  210.         anywhere else.
  211.  
  212.    INPUT(S)
  213.  
  214.         handle    - a valid handle
  215.         buffer    - a pointer to a valid SV_GfxBuffer
  216.         future    - always NULL yet
  217.  
  218.    RESULT
  219.  
  220.         NULL or an adequate SVERR-Errorcode.
  221.  
  222.    SINCE
  223.  
  224.         ... Version 1 SVDrivers.
  225.  
  226.    SEE ALSO
  227.  
  228.         SVD_DisplayGfxBuffer
  229.  
  230. -----------------------------------------------------------------------------
  231.  
  232.    NAME
  233.         SVD_DisplayGfxBuffer
  234.  
  235.    SYNOPSIS
  236.  
  237.         ULONG SVD_DisplayGfxBuffer(APTR handle, future)
  238.         D0    -$3c                 A1           A2
  239.  
  240.    FUNCTION
  241.  
  242.         Displays the GfxBuffer (which has been set via SVD_SetGfxBuffer before)
  243.         in the way, which is native to this SVDriver (e.g. on an Intuition
  244.         Screen, an EGS-Screen or into NIL ...)
  245.  
  246.    INPUT(S)
  247.  
  248.         handle    - a valid handle
  249.         future    - always NULL yet
  250.  
  251.    RESULT
  252.  
  253.         NULL or an adequate SVERR-Errorcode.
  254.  
  255.    SINCE
  256.  
  257.         ... Version 1 SVDrivers.
  258.  
  259.    SEE ALSO
  260.  
  261.         SVD_SetGfxBuffer
  262.  
  263. -----------------------------------------------------------------------------
  264.  
  265.    NAME
  266.         SVL_SetScreenType
  267.  
  268.    SYNOPSIS
  269.  
  270.         ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  271.         D0    -$42              A1           D1          A2
  272.  
  273.    FUNCTION
  274.  
  275.         Specifies, which ScreenType the Screen should have, on which the
  276.         graphic is to be displayed later.
  277.  
  278.         This statement may have no effect, if the SVDriver uses non-Intuition
  279.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  280.         ignore this setting more or less).
  281.  
  282.    INPUT(S)
  283.  
  284.         handle - a valid handle
  285.         type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  286.         future - always NULL yet
  287.  
  288.    RESULT
  289.  
  290.         NULL or an adequate SVERR-Errorcode.
  291.  
  292.    SINCE
  293.  
  294.         ... Version 1 SVDrivers.
  295.  
  296.    SEE ALSO
  297.  
  298.         SVD_GetScreenAddress
  299.  
  300. -----------------------------------------------------------------------------
  301.  
  302.    NAME
  303.         SVD_SetWindowFlags
  304.  
  305.    SYNOPSIS
  306.  
  307.         ULONG SVD_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  308.         D0    -$48               A1           D1           A2
  309.  
  310.    FUNCTION
  311.  
  312.         Specifies, which Flags the Window should have, on which the
  313.         graphic is to be displayed later.
  314.  
  315.         This statement may have no effect, if the SVDriver uses non-Intuition
  316.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  317.         ignore this setting more or less).
  318.  
  319.    INPUT(S)
  320.  
  321.         handle     - a valid handle
  322.         flags      - valid WindowFlags, like e.g. WFLG_BACKDROP
  323.         future     - always NULL yet
  324.  
  325.    RESULT
  326.  
  327.         NULL or an adequate SVERR-Errorcode.
  328.  
  329.    SINCE
  330.  
  331.         ... Version 1 SVDrivers.
  332.  
  333.    SEE ALSO
  334.  
  335.         SVD_SetWindowIDCMP, SVD_GetWindowAddress
  336.  
  337. -----------------------------------------------------------------------------
  338.  
  339.    NAME
  340.         SVD_SetWindowIDCMP
  341.  
  342.    SYNOPSIS
  343.  
  344.         ULONG SVD_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  345.         D0    -$4e               A1           D1           A2
  346.  
  347.    FUNCTION
  348.  
  349.         Specifies, which IDCMP the Window should have, on which the
  350.         graphic is to be displayed later.
  351.  
  352.         This statement may have no effect, if the SVDriver uses non-Intuition
  353.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  354.         ignore this setting more or less).
  355.  
  356.    INPUT(S)
  357.  
  358.         handle - a valid handle
  359.         idcmp  - a valid set of IDCMP-Flags
  360.         future - always NULL yet
  361.  
  362.    RESULT
  363.  
  364.         NULL or an adequate SVERR-Errorcode.
  365.  
  366.    SINCE
  367.  
  368.         ... Version 1 SVDrivers.
  369.  
  370.    SEE ALSO
  371.  
  372.         SVD_Show
  373.  
  374. -----------------------------------------------------------------------------
  375.  
  376.    NAME
  377.         SVD_GetScreenAddress
  378.  
  379.    SYNOPSIS
  380.  
  381.         struct Screen *SVD_GetScreenAddress(APTR handle, future)
  382.         D0             -$54                 A1           A2
  383.  
  384.    FUNCTION
  385.  
  386.         While displaying, the address of the DisplayScreen is returned
  387.         by this function.
  388.         See example SourceCodes for more and detailed information.
  389.  
  390.         This statement may not return a pointer to the real DisplayScreen,
  391.         if the SVDriver uses non-Intuition ways of displaying or exporting
  392.         the GfxBuffer (e.g. EGS.svdriver uses EGS-Screens, which are not
  393.         compatible with Intuition Screens).
  394.         So NULL or a pointer to a Dummy-Screen (Workbench-Screen) might be
  395.         returned sometimes.
  396.  
  397.    INPUT(S)
  398.  
  399.         handle - a valid handle
  400.         future - always NULL yet
  401.  
  402.    RESULT
  403.  
  404.         A valid ScreenPointer or NULL.
  405.  
  406.    SINCE
  407.  
  408.         ... Version 1 SVDrivers.
  409.  
  410.    SEE ALSO
  411.  
  412.         SVD_GetWindowAddress
  413.  
  414. -----------------------------------------------------------------------------
  415.  
  416.    NAME
  417.         SVD_GetWindowAddress
  418.  
  419.    SYNOPSIS
  420.  
  421.         struct Window *SVD_GetWindowAddress(APTR handle, future)
  422.         D0             -$5a                 A1           A2
  423.  
  424.    FUNCTION
  425.  
  426.         While displaying, the address of the DisplayWindows is returned
  427.         by this function.
  428.         See example SourceCodes for more and detailed information.
  429.  
  430.         This statement may not return a pointer to the real DisplayWindow,
  431.         if the SVDriver uses non-Intuition ways of displaying or exporting
  432.         the GfxBuffer (e.g. EGS.svdriver uses EGS-Windows, which are not
  433.         compatible with Intuition Windows).
  434.         So NULL or a pointer to a Dummy-Window (Custom-Window on Workbench)
  435.         might be returned sometimes.
  436.  
  437.    INPUT(S)
  438.  
  439.         handle - a valid handle
  440.         future - always NULL yet
  441.  
  442.    RESULT
  443.  
  444.         A valid WindowPointer or NULL.
  445.  
  446.    SINCE
  447.  
  448.         ... Version 1 SVDrivers.
  449.  
  450.    SEE ALSO
  451.  
  452.         SVD_GetScreenAddress
  453.  
  454. -----------------------------------------------------------------------------
  455.